home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Cream of the Crop 26
/
Cream of the Crop 26.iso
/
bbs
/
tmg108.zip
/
SCRIPTS.DOC
< prev
Wrap
Text File
|
1997-05-09
|
74KB
|
1,656 lines
SCRIPTS.DOC Page 1
╒═════════════════════════════════════════════════════════════════════════╕
│ The Magic Gate version 1.08 │
│ Documentation May/June '97 │
│ (C) Copyright 1995 - 1997 All Rights Reserved │
│ Joseph O'Connor │
╘═════════════════════════════════════════════════════════════════════════╛
This game may be distributed in its original, unmodified form as
long as no money is made off of it. Please do not include the contents
of this archive in any CD, collection, or whatever without express written
permission of ME!
This file was written for all you gamers out there who want to have a
custom game going on on your system. Contained within are the secrets of
the universe.... No wait, that was the other document, this one has all the
information you will need to write areas for Magic Gate. What you will find
will shock, will stun, will even AMAZE you, so true believers, sit back and
enjoy the ride.
─═════════════════════════════════════════════════════════════════════════─
Introduction:
As you may, or may not know, The Magic Gate supports EXternal MODuleS which
can be written by anyone in any language whatsoever and you get to mess with
drop files and writing your own routines for things I've already done.
Don't get me wrong, that is the best route to go if you want to do something
totally slick and new. But if you don't need all the bells, whistles and
power of say, Turbo Pascal, C++ etc, you can still add something 100% unique
to your game. The answer lies within the power of ASCII scripts which can
be written with any word processor or text editor. This is new as of
version 1.02, but I have written several test scripts to test it as thorough
as possible. First I will go through the pre-defined variables and what
they reference, then a list of predefined commands, using examples if I
feel like it ;) etc... hopefully by the end you will understand enough of
the language to write a script. (I need to have more programmer friends,
all of the friends I had look at this had their head explode... <G>)
SCRIPTS.DOC Page 2
─═════════════════════════════════════════════════════════════════════════─
All about Variables:
Variables are EVERYWHERE. (Don't make me give examples..) TMG Scripting
Language (TMGSL?? whatever) has a bunch of variables, and a bunch of funny
looking strings that represent variables. There are 20 variables each,
of 80 bytes (characters) in length which can be used to store both numerical
and textual data (Don't ask me how it works, it just does). As well as
29 variables which are either 1 (On) or 0 (Off) or 2 (Maybe) (nevermind)...
These variables, and their contents can be accessed via escape codes in
the ASCII script file. It's example time kiddies! Okay, say you wanted
to print how much gold the character currently had on him/her. You would
write a line in the script file that looked just like this:
Writeln "Gold on Hand : ^CS18"
Say the character had 386 gold on had, the line would look like this:
Gold on Hand : 386
Amazing, isn't it? Don't worry about each command just yet, the variables
are what is going to make the program go... You can check the contents of
variables conditionally as well. You could check to see if the player had
any creature fights and then perform a certain action easily by doing
something like this:
If ^CS26 > 0
Writeln "You Have ^CS26 creature fights left today."
Endif
If the player doesn't have any forest fights left, then the Writeln statement
will not be executed, and neither would enything before the Endif.
Hopefully the fog is starting to lift from your brain and things have
become much clearer. No? Well, this is only Page 2
SCRIPTS.DOC Page 3
─═════════════════════════════════════════════════════════════════════════─
Variables of Gender :
^CA Character Name
^CB male/female, based on sex of character
^CC son/daughter, based on sex of character
^CD his/her, based on sex of character
^CE he/she, based on sex of character
^CF him/her, based on sex of character
^CG sir/ma'am, based on sex of character
^DA Name of Character's master
^DB male/female, based on sex of characters master
^DC son/daughter, based on sex of characters master
^DD his/her, based on sex of characters master
^DE he/she, based on sex of characters master
^DF him/her, based on sex of characters master
^DG sir/ma'am, based on sex of characters master
Using just these variables, you can make menus look gramatically correct
for EVERY character. Say you wanted to have a few lines of text, whether
its in a menu, or in Write/Writeln statements, that gives the person the
idea that they are going up to their master and kneeling at his/her feet.
Do something Just like this:
Writeln " You go up to ^DA and kneel at ^DD feet."
Writeln " ^DA acknowledges you and says :"
Writeln " 'What can I do for you my ^CC?'"
Lets use Martissa as your master, mastissa is female. You are Bob, you are
male. These 3 lines would look like this:
You go up to Martissa and kneel at her feet.
Martissa acknowledges you and says :
'What can I do for you my son?'
The pronouns will change based on gender and all that good gramatically
correct stuff.
That's some pretty nifty stuff, but it doesn't just stop there... I am
sure you will need to do a few more things with characters information
aside from what their gender is.
SCRIPTS.DOC Page 4
─═════════════════════════════════════════════════════════════════════════─
About Character Related Variables:
All of the following commands will give you some sort of information
about the character. This all can be used just as has been described
before. These can also be modified using the commands in the script.
(Like ADD and SET). Obviously, string variables cannot be added to, but
can still be SET, (using SETSTR). I don't allow scripts to change :
A.)Characters Real Name, or B.)Characters Level in any way shape or form.
Some of these variables I don't allow a SET command to be used on simply
because I'd rather you just Added to and subtracted from. There are only
three (Attack,Defense, and Damage Reduction) so when you go to
Set ^CS03 4500
and it doesn't do anything, you'll know why. The following is legal, though
Add ^CS03 4500
It will add 4500 to attack, so I'm relying on you script writers not to
make the game too easy.
Some of the variables work differently whether you are modifying it or just
displaying it. The variable for guild is a good example.
^CS09 Will give you the name of the guild when used in a Write/Writeln
but the guild number is used everywhere else ^CS09 is found.
Refer to the next page for details on all the variables.
SCRIPTS.DOC Page 5
─═════════════════════════════════════════════════════════════════════════─
^CS Variables : Their Numbers and their Meanings
^CS01 Name (same as ^CA)
^CS02 *Real Name*
You cannot modify this variable at all.
Can only use in a Write type command or comparison.
^CS03 Attack Value
You cannot use the Set command on this variable
^CS04 Defense Value
You cannot use the Set command on this variable
^CS05 Damage Reduction Value
You cannot use the Set command on this variable
^CS06 Charm
^CS07 Shame
^CS08 Luck
^CS09 * Guild*
When used in a Writeln, it will display the name of the guild.
You cannot use the Add command on this variable
When used in a Set, it is the guild # (Included in case you want
your script to say kick a character out of their guild, or only
allow guilded characters into a certain area)
^CS10 Hit Points (Curr)
^CS11 Hit Points (Max)
^CS12 Current attack value of Equipped Weapon (See ^CS29 for max)
Note : Increasing Weapon Value does not increase Attack Value
^CS13 Name of currently Equipped Weapon
^CS14 Current defense value of Equipped Armor (See ^CS30 for max)
Note : Increasing Armor Value does not increase Defense Value
^CS15 Name of currently Equipped Weapon
^CS16 Current resistance value of Equipped Shield (See ^CS31 for max)
Note : Increasing Shield Value does not increase Damage Reduction
^CS17 Name of currently Equipped Weapon
^CS18 Gold on Hand
^CS19 Gold in Bank
^CS20 Gems
^CS21 Experience
^CS22 *Characters Level*
You cannot modify this variable at all.
Can only use in a Write type command or comparison.
^CS23 # of Skill Uses Curr
^CS24 # of Skill Uses Max
^CS25 *Characters Current location*
When used in a Writeln, the first character is ignored as it is
used to denote what type of zone the character is in.
You cannot use the Add or Set command on this variable
When used in a Location command, you must include the zone type
character (i.e. you would have Location "gGraveyard of Souls" as
opposed to Location "Graveyard", it just wouldn't display right)
^CS26 # of Creature Fights Left
^CS27 # of Player Fights Left
^CS28 Class
Only gives the current class of the character (Thief, Ranger etc)
^CS29 Maximum attack value of Equipped Weapon (See ^CS12 for curr)
Note : Increasing Weapon Value does not increase Attack Value
^CS30 Maximum defense value of Equipped Armor (See ^CS30 for curr)
Note : Increasing Armor Value does not increase Defense Value
^CS31 Maximum resistance value of Equipped Shield (See ^CS31 for curr)
Note : Increasing Shield Value does not increase Damage Reduction
SCRIPTS.DOC Page 6
─═════════════════════════════════════════════════════════════════════════─
About Script Related Variables:
What is a program that doesn't communicate with itself? If it doesn't know
if you've opened the door, how is it supposed to know whether or not you can
go through it? Script Related variables fill this gap quite nicely. You
should have more than enough variables to do whatever you need to do in a
script.
There are 20 variables that can be displayed/set/setstr/add/mult whatever
you want to do til your heart's content. Each variable can contain up to
80 bytes, which is more than plenty for any number you may want to store,
or just right if it is going to be used for output to the player.
There are 29 more variables that are either 0 or 1 (False or True) (boolean
if that means anything to you) that can be used as flags to let the script
know that something has been performed (without having to waste a ton of
variable space on it).
The script related variables are accessed just like character based
variables except they all start with ^VR.
^VR01 Script Variable #1
^VR02 Script Variable #2
....
....
^VR19 Script Variable #19
^VR20 Script Variable #20
Note again that you must have a leading 0 for 01-09. Well, those aren't
the only variables that start with ^VR.... there are really more variables
that have the prefix ^VR... They are special in that you cannot use them
in the Set/Setstr/Add/Mult command. They contain certain parameters about
the game that have been set. As you will learn, script files can read in
external creature files. The script knows which file to read by reading
the command : CreatureFile NAME.EXT somewhere in the script file (I would
suggest putting it in the @#Define section (which you will learn about
later). That creature file-name is stored as ^VR22. There is a command
called DefaultCommand that is used to set up what input defaults to when
a prompt comes up. Say you perfrom a DefaultCommand L. Anytime thereafter
a prompt comes up, if the player just hits enter, the input will actually
be L. This will be the case until the DefaultCommand is called again.
The default command is stored in ^VR21. To sum it up, the "special"
variables are :
^VR21 The current default command.
This command is set using the DefaultCommand command
^VR22 The current creature file to read creatures from.
This command is set using the CreatureFile command
^VR23 Stores the Character Boolean flags. (See the ^GF variables)
^VR24 The current menu file to read menus from.
This command is set using the MenuFile command
^VR25 The current item file to read items from.
This command is set using the ItemFile command
Note : These commands can only be used in a Write/Writeln/ or comparison.
(See the corresponding command in the commands section for more details)
SCRIPTS.DOC Page 7
─═════════════════════════════════════════════════════════════════════════─
About Boolean Variables:
Remember I talked about those variables that could be 0 or 1? Well, I call
those Game Flags, hence the reason they are accessed using the ^GF prefix.
There are currently 29 of those available (believe it or not, that is not
just an arbitrary number). These can be used for numerous things. I use
them to tell the script whether the player has performed a certain action
or not. Like for instance, whether they have examined the door in the room
or not (hint if you need it in The Crypt of Lord Hamilton)...
This type of variable cannot be used in Add/Setstr, but can be used in
Set/Write/Writeln/or comparisons. Note, that it can only be set to 0 or 1.
Note again that you must have a leading 0 for 01-09.
^GF01 Game Flag #1
^GF02 Game Flag #2
....
....
^GF28 Game Flag #28
^GF29 Game Flag #29
Any ^GF variable can only be 0 or 1 (maybe 2, but I wouldn't push it, the
computer may decide it doesn't want to compute anymore ;)
─═════════════════════════════════════════════════════════════════════════─
About Boolean Variables - The Character Flags :
Each character has a series of flags that the game keeps track of (29
to be exact... hmmm, haven't I seen 29 of something before? hint : 29
is the limit of booleans available in a longint :) Anyway, these are
alot like the Game Flags I just talked about, except that these are used
by the main portion of the game as well, and stored in the character
file. There really isn't a need to be setting these, but it is okay to
look at them (to see if say, the character is drunk ;) and use them in
a script. They are accessed using the ^CX prefix. This variable will
be either a 0 or a 1. Note, a leading zero is necessary for 01-09.
^CX01 Character Flag #1
^CX02 Character Flag #2
....
....
^CX28 Character Flag #28
^CX29 Character Flag #29
SCRIPTS.DOC Page 8
─═════════════════════════════════════════════════════════════════════════─
Construction of a script:
Scripts are pretty easy-going as far as layout goes. The sections do
not need to be in a particular order, upper/lowercase is ignored for
section names and variables etc. Sections are defined in the script
file by putting the characters @# at the start of a line and the section
name of the script immediately following. If I wanted a section for
fighting creatures in my script, I might call it Fight and would therefore
have a section in my script defined as the following :
@#Fight
To designate the end of the file, put a @# as the last line in the script.
While the physical order of the sections in the script file has no bearing
on its functionality, there is a certain order of execution that is built
into the interpretter. The script begins execution by looking for the
@#DEFINE section. It is not necessary to have a define section, but this
section is special in that it is only looked at once, and therefore, any
variables that are to be used to keep track of something important should
be initialized here. Also, using the Location <name> command in the define
section is a good idea so that the character doesn't appear to be stuck at
the town square <G>. I would also set the inital CreatureFile here so you
don't forget to do it.
There are some section names that have a special meaning to the script
language. I've already mentioned the define section. The Define section
is the first section the game looks at in a script. After it reads and
executes all the commands in the Define section, it jumps to the section
in the script with the name "Main" (without the quotes) and begins the
main section of the game.
NOTE : Every section in the script file that is to be executed can be
thought of as a never-ending loop, and without a return or a halt command
somewhere within the section, you will never leave it. (exception @#DEFINE)
*** NEW 1.07 ***
As of version 1.07, the MagiCfg program contains a new section used for
ExMod additions and removals and modifications. It is possible to add any
program under the TMG directory to the 'Other Realms' menu using this
feature. In addition, built in is the ability to read either the script
or a special description file to retrieve both the name of the ExMod and
the description and add those to the Other Realms menu. To accomplish this
within a script is simple. Add a section to the script that looks like
the following example:
@#INSTALL
<The name of the script goes on the first line>
<The description of the script continues after that>
<...>
<...>
<End of description>
@#OTHER_SECTIONS
SCRIPTS.DOC Page 9
─═════════════════════════════════════════════════════════════════════════─
It is nearly as easy to do this for programs that do not end in .SCR which
include compiled scripts, Executable programs and/or batch files. Create
a file with the same name as your program but use a .DSC extension. Within
that file include the following:
@#INSTALL
<The name of the script goes on the first line>
<The description of the script continues after that>
<...>
<...>
<End of description>
@#
Looks just like the example for the scripts because it actually reads it
the exact same way. If this method was not included with a ExMod then
it installs the ExMod with a generic name and no description. These can
then be easily modified.
─═════════════════════════════════════════════════════════════════════════─
@#MONSTER
Another section name the game could look into is @#MONSTER which is where
you define any monsters internal to the script.
NOTE : Using internal creatures is the only way to guarantee exactly which
creature a character will fight at any given time, so if you have a "boss"
at the end of your script, make him/her an internal creature.
The following is how you would define an internal creature. The second
word on any of the lines must be the creatures internal number (The number
you pass to Combat when you want the player to fight an internal monster.
STATS <num> <attack> <defense> <shield> <exp> <gold> <hit points> <level>
NAME <num> "<Monsters Name>"
WNAME <num> "<Monsters Weapon Name>"
ANAME <num> "<Monsters Armor Name>"
DEATH <num> "<Monsters Death Line>"
Those lines do not have to be in any particular order (I just remember them
that way ;) But you must have all 5 lines present to get a complete monster.
─═════════════════════════════════════════════════════════════════════════─
@#ITEMS
As of Version 1.07, there is another "special" section in a script file :
@#ITEMS
This is where you will define all the items that are going to be given away
in your script.
The following is how you would define an item. The second word on any of
the lines must be the items number (The number you pass to Item when you
want to give that item to the player). These numbers have no meaning at
all outside the script, it is just for internal reference.
NAME <num> "<Item Name>"
SCRID <num> "<Item ScriptID>"
STAT1 <num> attack maxattack cost charges wear_location
STAT2 <num> required_level item_flags identified?
SCRIPTS.DOC Page 10
─═════════════════════════════════════════════════════════════════════════─
Item Definitions:
Okay, and so you know what those values should be, here are their
definitions.
Item Name - This is the name the character sees in his inventory and is
used for all display purposes.
Item ScriptID - This is a unique code that you (the creator) assign to
the item you create. This is what it will be referenced with
in the database file. The standard formula for this should
be as follows: LLLL-MMDDYYYY-LL-L
LLLL is 4 characters to identify the item
MM is the 2 digit month the item was created
DD is the 2 digit day of the month the item was created
YYYY is the 4 digit year the item was created
LL are the creators initials
L is either Y or N - Y allows other items to access your items
scripts as if they were its own. N means nothing else can use
the scripts for this item.
Attack - The value the item adds to your combat value. This is the
attack value for weapons, defense for armor, and damage resistance
for shields. This should be 0 for all non weapon/armor/shields.
MaxAttack - The maximum value the item can add to your combat value.
(see Attack above for more information as well.)
Cost - What you would pay for this item if you were to buy it in one
of the shops. (also what selling it is based upon)
Charges - This is how many times the item can be used. Charges are
subtracted from the item on any "USE", "ONDEATH", or "USECOMBAT"
When the last charge is used, that fires the "LASTUSE" script
if the item has one
Wear_Location - What type of item is this, and where can I equip it?
This will be a number that corresponds to one of the following:
1 - Head 6 - Feet
2 - Neck 7 - Weapon
3 - Armor 8 - Shield
4 - Hands 9 - Treasure
5 - Ring 10 - Other
Required_Level - The level the character must be to use this item.
Item_Flags - These are miscellaneous special effects that the object can
have, and can be used to make the item unique
1 - Item Disappers on its final use (potions etc...)
2 - Silver (useful against werewolves etc)
4 - Magic +1 (certain monsters require at least a magical
8 - Magic +2 item to be hit. Monsters will have the
16 - Magic +3 same flags for to be hit.)
(more to come)
Identified - Does the character recognize this item for what it is as
soon as he/she gets it, or do they need to Identify it?
Values for this are:
0 - Not Identified 1 - Identified
SCRIPTS.DOC Page 11
─═════════════════════════════════════════════════════════════════════════─
Setting up Item Scripts:
There are currently 10 different actions you can apply to your items.
They are in their own section of the script denoted with the following
syntax
@#ITEM<NUM>_<ACTION>
......
......
@#ITEM<NUM>_<ACTION>
etc..
Where NUM is the item number as it is defined in the @#ITEMS section
(NAME 1 "Sword of Killing" would be designated as @#ITEM1_<ACTION>)
and where <ACTION> is on what type of event the script for that section
goes off. The list of Actions is as follows :
WEAR *ONATTACK USECOMBAT
USE *ONDAMAGE IDENTIFY
REMOVE **ONDEATH LASTUSE
DROP
*This command is not yet implemented, but here to show how much can be
done with the system
**This command currently only triggers on death in a creature fight (not
a master level up fight or a player fight)
Example of a Potion of Healing:
@#ITEMS
NAME 1 "`2Potion of Healing"
SCRID 1 "PofH-04111997-JO-N"
STAT1 1 0 0 2500 1 10
STAT2 1 1 1 0
@#ITEM1_USE
Writeln "`3 You take a drink of the Potion of Healing and a warm fire"
Writeln "shoots through your body. It magically heals your wounds and"
Writeln "completely heals you."
Set ^CS10 ^CS11
@#ITEM1_USECOMBAT
Gosub USE
@#ITEM1_IDENTIFY
Writeln "`3 The Potion of Healing will restore your Hit Points to Maximum when"
Writeln " the potion is used."
Writeln "`9 (`%Heals all wounds`9)"
@#ITEM1_LASTUSE
Writeln "`9 (`%The vial is now empty`9)"
This item would have the following information:
Name : (Green)Potion of Healing(Green)
Script ID : PofH-04111997-JO-N
Attack : 0
Max Attack: 0
Cost : 2500
# Charges : 1
Worn at : Other
Req. Level: 1
Flags : Disappears after its last use
Ifentified: No
Scripts : USE USECOMBAT IDENTIFY LASTUSE
SCRIPTS.DOC Page 12
─═════════════════════════════════════════════════════════════════════════─
Example of a script:
@#Define
CreatureFile MYGRAVE.DAT
Set ^VR19 0
Set ^VR20 0
Location "gMt. Dead Graveyard"
@#MAIN_MENU
EGL
`c `%Gates of Mt. Dead :
`#-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
`9 You stand before the looming gates of Mt. Dead, the notorious place to
`9 find all manner of creature living or dead. Can you handle what this
`9 place will throw at you?
`3
`3 (`#E`3)xamine the Gates.
`3 (`#G`3)o Boldly In.
`3 (`#L`3)eave this scary place.
@#MAIN
Menu MAIN_MENU
Writeln ""
Writeln " `%Mount Dead :"
DefaultCommand G
ReadMenuCommands ^VR01
Writeln "^VR01"
If ^VR01 == E
Writeln "`! You see nothing unusual about the gates."
Endif
If ^VR01 == G
Gosub DEAD1
Endif
If ^VR01 == L
Halt
Endif
If ^VR01 == R
DisplayRanks
Endif
If ^VR01 == V
DisplayStats
Endif
If ^VR01 == F
FindPlayers
Endif
@#
Note : The section that contains the menu and the section that contains
executable code are defined the exact same way. The only difference is
the way they are accessed. A Menu is brought to the user and displayed
through use of the Menu command, a sub-section is made current with the
Gosub/Return Command.
SCRIPTS.DOC Page 13
─═════════════════════════════════════════════════════════════════════════─
Command Index:
Command Page
Add................................................................ 14
Combat............................................................. 14
CreatureFile....................................................... 15
DefaultCommand..................................................... 15
DisplayCreatures................................................... 15
DisplayGameStats................................................... 16
DisplayMenu........................................................ 16
DisplayRanks....................................................... 16
DisplayScriptInfo.................................................. 17
DisplayScriptText.................................................. 17
DisplayStats....................................................... 17
FindPlayers........................................................ 18
Gosub.............................................................. 18
GotoXY............................................................. 18
Halt............................................................... 19
Healer............................................................. 19
If/Endif........................................................... 19
Inventory.......................................................... 20
Item............................................................... 21
ItemFile........................................................... 21
Location........................................................... 22
Mail/MailCommands/EndMail.......................................... 22
Menu............................................................... 23
MenuFile........................................................... 23
MessageBoard....................................................... 23
MonsterAvailable................................................... 24
Mult............................................................... 24
Pause.............................................................. 24
Random............................................................. 25
ReadChar........................................................... 25
ReadLine........................................................... 25
ReadMenuCommands................................................... 26
ReDispMenu......................................................... 26
Return............................................................. 27
Set................................................................ 27
SetStr............................................................. 27
SharedEvent........................................................ 28
Write.............................................................. 28
Writeln............................................................ 29
WriteBlock/EndBlock................................................ 29
─═════════════════════════════════════════════════════════════════════════─
Flag Related Commands
AddFlag............................................................ 30
RemoveFlag......................................................... 31
FlagValue.......................................................... 32
SCRIPTS.DOC Page 14
─═════════════════════════════════════════════════════════════════════════─
Command Descriptions :
Add
────────────────────────────────────────────────────────
Syntax : Add <Variable> <Amount>
Description : Adds the amount specified in the second parameter to
the variable specified in the first parameter.
Notes : <Variable> can be any type of variable from the ^VR
or ^CS fields that contains an integer value. There
are also a few other fields which are excluded.
<Amount> can be a literal (i.e. 2, 8, 32000 etc.) or
it can be a variable from the ^VR or ^CS or ^GF
fields that contains an integer value. A negative
sign in front of the literal, or variable will tell
the routine to SUBTRACT the amount from the variable.
Exclusions : <Variable> cannot be :
^CS01 ^CS02 ^CS09 ^CS13 ^CS15 ^CS17 ^CS22 ^CS25
Examples :
Add ^CS18 320
Add ^CS10 -5
Add ^CS10 -^VR03 (Assuming ^VR03 has an integer in it)
Add ^VR18 ^CS26
Combat
────────────────────────────────────────────────────────
Syntax : Combat <Variable> Int/Ext | <Creature Number>
Description : Puts the player into combat versus a creature.
Saves the result of the combat in <Variable>.
Variable will be :
0 : Character ran away from creature.
1 : Character defeated creature.
2 : No creature was available (level/<num> error)
Notes : This is the one routine where you can have a
^GF variable equal to 2. I would not suggest
doing it on a frequent basis, but, it does the job.
Int/Ext, set to Int and include the
<Creature Number> to have the creature the player
fights to be a specific creature in the @#MONSTERS
section of the script file. Set to Ext to have
the script pick a random monster of the players
level from the filename stored using CreatureFile.
Exclusions : Don't use any of the ^CS variables as the <Variable>
That's just asking for trouble.
Examples :
Combat ^VR19 Ext
Combat ^GF26 Ext
Combat ^GF29 Int 1
Combat ^VR14 Int 8
SCRIPTS.DOC Page 15
─═════════════════════════════════════════════════════════════════════════─
Command Descriptions :
CreatureFile
────────────────────────────────────────────────────────
Syntax : CreatureFile <FileName>
Description : Assigns the external file to read creatures from
when a Combat Ext command is executed.
Notes : Usually this will not change throughout the course
of the script. I recommend putting this command
in the @#Define section of the script to avoid
executing it every loop.
Examples :
CreatureFile FOREST.DAT
CreatureFile CRYPT.DAT
DefaultCommand
────────────────────────────────────────────────────────
Syntax : DefaultCommand <Command>
Description : Assigns what command is chosen when the player
strikes enter at the input lines thereafter.
Notes : <Command> can be any variable, including menu
commands ^MC##, ^GF##, ^CS##, ^VR##. If the
default command is set to more than one character
and a ReadChar is encountered, only the first
character in <Command> will be executed.
Examples :
DefaultCommand L
DefaultCommand ^MC02
DefaultCommand ^CS18
(Will make the default command the amount of
gold they have on them (good for donations))
DefaultCommand ^VR12
DisplayCreatures
────────────────────────────────────────────────────────
Syntax : DisplayCreatures
Description : This command will bring up a display of all the
creatures currently loaded into the script.
Notes : This command is here for test purposes really.
Use it when you want to see what creatures are
available for the combat routine
(Currently only works with EXTernal creatures)
SCRIPTS.DOC Page 16
─═════════════════════════════════════════════════════════════════════════─
Command Descriptions :
DisplayGameStats
────────────────────────────────────────────────────────
Syntax : DisplayGameStats
Description : This command will bring up a display of all the
statistics of the game, saved in the MAGISTAT.DAT
file.
Notes : This command includes most any stat about the game
you would want or need to know, including how many
characters are in the game, deletion period etc.
DisplayMenu
────────────────────────────────────────────────────────
Syntax : DisplayMenu
Description : This command will display the menu loaded into
into the current section of the script to the player.
Notes : This command is best used after the ReadMenuCommands
command in an If statement. I have always used ?
as the command to redisplay the menu
Example :
Menu Main_menu
ReadMenuCommands ^VR01
If ^VR01 == ?
DisplayMenu
Endif
DisplayRanks
────────────────────────────────────────────────────────
Syntax : DisplayRanks
Description : This command is used to display the rankings of
the players to the player.
Notes : This is a call to the same command the main part
of the game calls. I would use an R as the command
to display the ranks.
Example :
Menu Main_menu
ReadMenuCommands ^VR01
If ^VR01 == R
DisplayRanks
Endif
SCRIPTS.DOC Page 17
─═════════════════════════════════════════════════════════════════════════─
Command Descriptions :
DisplayScriptInfo
────────────────────────────────────────────────────────
Syntax : DisplayScriptInfo
Description : This command should be used for debugging a script.
It will display the section of the script it is
currently running, the creature file, the current
default command and the contents of the 49 variables.
Note : Do not include this in the final version of the
script as it could give a player quite a bit of
insight into the script (which it does give)
DisplayScriptText
────────────────────────────────────────────────────────
Syntax : DisplayScriptText
Description : This command should be used for debugging a script.
It will display the actual text in that section of
the script.
Note : Do not include this in the final version of the
script as it could give a player a look at all of
the commands in the current section. This is good
for figuring out if something is out of place in
the script.
Example :
Menu Main_menu
ReadMenuCommands ^VR01
If ^VR01 == -
DisplayScriptText
Endif
DisplayStats
────────────────────────────────────────────────────────
Syntax : DisplayStats
Description : This command is used to display the statistics
of the character to the player.
Notes : This is a call to the same command the main part
of the game calls. I would use a V as the command
to display the stats.
Example :
Menu Main_menu
ReadMenuCommands ^VR01
If ^VR01 == V
DisplayStats
Endif
SCRIPTS.DOC Page 18
─═════════════════════════════════════════════════════════════════════════─
Command Descriptions :
FindPlayers
────────────────────────────────────────────────────────
Syntax : FindPlayers
Description : This command is used to display the current
location of all players currently in the game.
Notes : This is a call to the same command the main part
of the game calls. I would use a F as the command
to display the stats.
Example :
Menu Main_menu
ReadMenuCommands ^VR01
If ^VR01 == F
FindPlayers
Endif
Gosub
────────────────────────────────────────────────────────
Syntax : Gosub <SectionName>
Description : This command is used to jump from one section
in the script file to another.
Notes : This is a great way to seperate "rooms" in the
game, or put a commonly used set of commands in
its own section and have whatever needs to access
it call it with a Gosub/Return (see the corresponding
section on Return as well). Be sure not to gosub to
a section you have written as a menu section.
Example :
Menu Main_menu
ReadMenuCommands ^VR01
If ^VR01 == D
Gosub DoSomething
Endif
If ^VR01 == K
Gosub KillSomething
Endif
GotoXY
────────────────────────────────────────────────────────
Syntax : GotoXY <X coord.> <Y coord.>
Description : This command jumps the cursor to the screen
coordinates specified in the X and Y coords.
Note : This can be used to make screens with text
placed anywhere necessary without using a
ton of Writeln "" 's.
Example : GotoXY 1 1
This will take the cursor to the home position.
SCRIPTS.DOC Page 19
─═════════════════════════════════════════════════════════════════════════─
Command Descriptions :
Halt
────────────────────────────────────────────────────────
Syntax : Halt
Description : This command is used to stop the execution
of the script.
Notes : Halt can be placed anywhere in the script as
well as as many occurances of it as are necessary.
Healer
────────────────────────────────────────────────────────
Syntax : Healer
Description : This command will take the character to the
healers hut and return them exactly where they
were when they entered.
Notes : This is a call to the same command the main part
of the game calls.
If/EndIf
────────────────────────────────────────────────────────
Syntax : If <variable1> <operator> <variable2>
Description : These commands are used to make a decision within
the script.
Notes : This command is a major portion of what a script
does. It can determine what letter is stored
within a certain variable, whether a characters
hit points/level/luck is equal to or less than, or
greater than a certain number/variable.
Variables of all types are allowed on BOTH sides of
the operator.
Operater is one of the following
If a == b a is equal to b
If a <> b a is not equal to b
If a >= b a is greater than or equal to b
If a <= b a is less than or equal to b
If a > b a is greater than b
If a < b a is less than b
Note that there must be 3 seperate "words" on the
line (A space must exist between the variables and the
operator)
If a statement is found to be true, everything until the
next EndIf is executed. If it is false, the script finds
the command immediately following the next EndIf and begins
executing from that point onward.
SCRIPTS.DOC Page 20
─═════════════════════════════════════════════════════════════════════════─
Command Descriptions :
If/EndIf continued.
────────────────────────────────────────────────────────
Notes : If can be used to compare all manners of variables,
whether they contain numbers or strings, it will
work with it. Be warned though, the only operators
that you should used with string are the == and the <>.
You can use the other operators with strings, but
if you are not sure of what you are doing, you may
get unexepected results.
Example : Menu MainMenu
ReadMenuCommands ^VR01
Writeln "^VR01"
If ^VR01 == A
Writeln "Hey, you hit A"
Endif
If ^VR01 == L
Writeln "Hey, you hit L"
Endif
If ^VR01 >= 1
If ^VR01 <=9
Write "^VR01 squared = "
Mult ^VR01 ^VR01
Writeln "^VR01"
Endif
Endif
Inventory
────────────────────────────────────────────────────────
Syntax : Inventory
Description : This command brings up the (Y)our Inventory screen that
is accessible from the main menu and allows you to identify,
equip, remove, and drop items.
Notes : This command should be accessible from any main menu within
a script file.
SCRIPTS.DOC Page 21
─═════════════════════════════════════════════════════════════════════════─
Command Descriptions :
Item
────────────────────────────────────────────────────────
Syntax : Item <Item Number> [NODISPLAY]
Description : This command gives the character the item in the script
that is specified by <Item Number>.
Notes : This item must exist in the @#ITEMS section of the script
or the @#ITEMS section of the file specified in the ItemFile
command (see ItemFile). If the item has never been given out
before, the game will create an Item Registry entry for it in
ITEMS.DAT and will create the script to go along with the item
in the items/ subdirectory. See the section on Item Definition
for full details on how to create the item definition
a script file.
If you put a NODISPLAY as the second parameter (after the
item number), TMG will _NOT_ output anything to the user,
but will let your script do all of that.
Example :
Item 1
Item ^VR04
Item 3 NODISPLAY
ItemFile
────────────────────────────────────────────────────────
Syntax : ItemFile <FileName>
Description : Assigns the external file to read item from when an
Item command is issued (see Item)
Notes : Usually this will not change throughout the course
of the script. I recommend putting this command
in the @#Define section of the script to avoid
executing it every loop.
Examples :
ItemFile FOREST.ITM
ItemFile CRYPT.ITM
SCRIPTS.DOC Page 22
─═════════════════════════════════════════════════════════════════════════─
Command Descriptions :
Location
────────────────────────────────────────────────────────
Syntax : Location "<location name>"
Description : This command sets the characters location to whatever
is contained within the quotation marks.
Notes : The area type character must be included in this command.
The available area type characters are :
B -Generic Building C -Cave
D -Dungeon F -Forest
G -Graveyard H -Guild Hall
K -Castle M -Mountains
R -Road S -Shop
T -Town I -Inventory
The Location of the character can change as often as
you need it to. This can be useful in case you are writing
a script as say a forest, and you have a main boss that you
want the all character to fight without the special ranger
power for the forest, set the location (temporarily) to
"T<script name>" and the power will be disabled.
Mail/MailCommands/EndMail
────────────────────────────────────────────────────────
Syntax : Mail <to> <from>
<Mailbody>
....
....
MailCommands
<Commands>
....
....
EndMail
Description : This sequence of commands is used to put mail in the
file for the character specified in <to> from <from>
with <Mailbody> as the text and execute whatever
commands are in the <Commnads> section.
Notes : The <To> portion of the mail command can only be one
word. This shouldn't be a problem since you will more
than likely be using a variable for that. The <from>
portion, however, does not have that limitation. <from>
can be a variable, it can be a literal, and does not
need enclosing quotation marks. I picture using a variable
here most often as well.
Example : Mail ^CS01 System Message :
`9You have been penalized by the gods for your insubordination.
`9You lose EVERYTHING!
MailCommands
Set ^CS18 0
Set ^CS19 0
Set ^CS20 0
EndMail
SCRIPTS.DOC Page 23
─═════════════════════════════════════════════════════════════════════════─
Command Descriptions :
Menu
────────────────────────────────────────────────────────
Syntax : Menu <MenuName>
Description : This command sets a certain section of the script file
as the menu to be displayed to the character for the
section of the script the game is currently executing.
Notes : Make sure you don't set an executable section of the
script as a menu in the game (would look a bit silly
to the user ;)
Example : Menu FOREST_TREES
Menu Enter_Building
MenuFile
────────────────────────────────────────────────────────
Syntax : MenuFile <FileName>
Description : Assigns the external file to read menus from
when a menu command is executed.
Notes : Usually this will not change throughout the course
of the script. This variable defaults to the script
file itself, so if you put all of your menus in the main
script file, you should not set this.
Examples :
MenuFile FOREST.MNU
MenuFile CRYPT.MNU
MessageBoard
────────────────────────────────────────────────────────
Syntax : MessageBoard <Number> <Title of Board>
Description : This command will allow the user to read and post messages
on a bulletin board.
Notes : The number is the key as to which bulletin board it is,
not the Title. Each of the numbers (1-99) creates a
unique bulletin board for that script. If you want people
to be able to read and post to the same bulletin board from
two different locations, you just make sure they have the
same number
SCRIPTS.DOC Page 24
─═════════════════════════════════════════════════════════════════════════─
Command Descriptions :
MonsterAvailable
────────────────────────────────────────────────────────
Syntax : MonsterAvailable <Variable>
Description : This command sets the variable to a 1 if there is a
monster available in the CreatureFile of the same level
as the character, and a 0 if there is not.
Notes : If no creature file has been set, this command will
always set the variable to 0 (since the won't be ANY
monsters in the file). This is a good way of determining
if the character is in the proper area for a character of
his/her level.
Example :
MonsterAvailable ^GF28
If ^GF28 == 1
Combat ^GF29 Ext
Return
Endif
Writeln "`9 There is nothing here for you to fight."
Mult
────────────────────────────────────────────────────────
Syntax : Mult <Variable> <number>
Description : This command is used to multiply a variable by a certain
number, and store the results back in the variable.
Notes : The number portion of the command can also be a variable
of any type. Note that this command will overwrite the
number existing in the variable. If a string is set in
either of the variables, the result will be 0.
Example :
Set ^VR02 5
Mult ^VR02 ^CS22
Writeln "Your level *5 = ^VR02"
Pause
────────────────────────────────────────────────────────
Syntax : Pause
Description : This command is used to print the Hit Any Key message to
the user and suspend execution until a key is pressed.
Notes : This is a call to the same command the main part
of the game calls. I would use it so a user can
read anything you put on the screen before you clear
it.
SCRIPTS.DOC Page 25
─═════════════════════════════════════════════════════════════════════════─
Command Descriptions :
Random
────────────────────────────────────────────────────────
Syntax : Random <Variable> <number>
Description : This commad is used to generate a random number from
1 - <number> and store is in <Variable>.
Notes : The number portion of the command can also be a variable
of any type. Note that this command will overwrite the
number existing in the variable. If a string is set in
the <number> section, the result will be 0.
Example : Random ^VR04 ^CS22
(Picks a random number from 1-character level and stores
it in ^VR04)
ReadChar
────────────────────────────────────────────────────────
Syntax : ReadChar <Variable>
Description : This command stops and waits for the user to press a
key, and then stores that character in <Variable>
Notes : The input is disconnected from what type of character
the user hits. If they put in a number, the operations
dealing with numbers will work on it and if they put in
a string, the operations dealing with numbers will not
work on it.
Example : ReadChar ^VR02
If ^VR02 == C
Writeln "You pressed C"
Endif
ReadLine
────────────────────────────────────────────────────────
Syntax : ReadLine <Variable>
Description : This command stops and waits for the user to enter
a line of text and press enter, and then stores that
line of text in <Variable>
Notes : The input is disconnected from what type of line the
user enters. See the notes on ReadChar for exact details.
Example : DefaultCommand ^CS18
Write "How Many Gold Pieces to Donate? [^VR21] : "
ReadLine ^VR03
If ^VR03 > 0
If ^VR03 < ^CS18
Add ^VR19 ^VR03
Add ^CS18 -^VR03
Endif
Endif
SCRIPTS.DOC Page 26
─═════════════════════════════════════════════════════════════════════════─
Command Descriptions :
ReadMenuCommands
────────────────────────────────────────────────────────
Syntax : ReadMenuCommands <Variable>
Description : This command first displays the commands that were
read in from the menu command, then displays the
Command : prompt along with the DefaultCommand then
stops and waits for the user to press a key and
stores that character in <Variable>
Notes : This should go shortly after the Menu Command in the
section of the script. Other than what it prints out,
the ReadChar command does the same function.
This command does NOT print out the character it reads.
Example :
Menu MAIN_MENU
DefaultCommand L
ReadMenuCommands ^VR01
Writeln "^VR01"
If .....
....
Endif
ReDispMenu
────────────────────────────────────────────────────────
Syntax : ReDispMenu <TRUE/FALSE>
Description : This command affects whether a menu is shown to a
character or not the next time the MENU command is
executed.
Notes : By default, every time the Menu command is executed,
the menu specified is displayed to the user. The
exception to this rule is when a section "bounces",
meaning when it gets to the end of the section and
goes back up to the top, the menu command is ignored.
When a Gosub/Return sequence is executed, the menu
will be re-read AND re-displayed after the "bounce".
To prevent this from redisplaying, you would use
a ReDisplMenu FALSE before the return.
Example :
@#FIGHT
Writeln ""
Writeln "You find nothing to fight"
ReDispMenu FALSE
Return
@#MAIN
Menu MAIN_MENU
ReadMenuCommands ^VR01
If ^VR01 == S
Gosub Fight
Endif
SCRIPTS.DOC Page 27
─═════════════════════════════════════════════════════════════════════════─
Command Descriptions :
Return
────────────────────────────────────────────────────────
Syntax : Return
Description : This command is the partner of Gosub. It will take
the scripts execution back to the next command in
the calling section and continue execution from that
point.
Notes : Remember to include this command. Without it, the called
section will repeat forever. Note : It is NOT necessary
to return back to the main loop before calling Halt.
Set
────────────────────────────────────────────────────────
Syntax : Set <Variable> <number>
Description : This command takes whatever is in number and stores that
value in <Variable>
Notes : The number portion of the command can also be a variable
of any type. Note that if the variable contains multiple
words (A long string for example), the variable will be
set to only the first word in the string (Use the SetStr
command instead).
Example :
Set ^VR02 4
Set ^VR03 ^CS18
Set ^VR04 ^VR20
Set ^GF 1
Set ^CS18 0
SetStr
────────────────────────────────────────────────────────
Syntax : SetStr <Variable> "<Text>"
Description : This command takes whatever <Text> is (containing multiple
words if necessary) and stores it in <Variable>
Notes : The <Text> portion of the command can contain any
combination of literals and variables, as the variables
will be expanded to their stored value.
Note : The maximum length of a variable is 80 characters.
The string is stored exactly as you type it, and any
variables are calculated when the line is printed out or
something is done with it, so the same line can be used
without having to Re-Set it every time.
Example :
SetStr ^VR02 "You have ^CS10 Hit Points Left"
SetStr ^VR03 "^CS01 is a stud!"
SCRIPTS.DOC Page 28
─═════════════════════════════════════════════════════════════════════════─
Command Descriptions :
SharedEvent
────────────────────────────────────────────────────────
Syntax : SharedEvent <Event Number> | 0
Description : This command causes a special event written into the
compiled code of the game to occur.
Notes : This will become useful as the game expands and more
events become available. This is here now so that the
old man in the wagon can be available in any scenario.
Passing 0 as the event number will have it choose one
at random.
Events : 1 Old Man in Wagon
Example :
If ^VR01 == S
If ^CS26 > 0
SharedEvent 1
EndIf
EndIf
Write
────────────────────────────────────────────────────────
Syntax : Write "<Text to Display>"
Description : This command will display the text between the quotation
marks to the user's screen, without a newline or a
carriage return.
Notes : Useful in conjunction with the ReadChar function for
one-key input.
Example :
@#Ask
DefaultCommand Y
Write " `9Leave Game, are you sure? (Y/N) [^VR21] : "
Readchar ^VR01
If ^VR01 == Y
Halt
Endif
ReDispMenu FALSE
Return
SCRIPTS.DOC Page 29
─═════════════════════════════════════════════════════════════════════════─
Command Descriptions :
Writeln
────────────────────────────────────────────────────────
Syntax : Writeln "<Text to Display>"
Description : This command will display the text between the quotation
marks to the user's screen, followed by a newline and a
carriage return.
Notes : Useful when displaying a line or two of text to the player
where there are few things on each line.
Example :
If ^VR02 == CRACK
Writeln "`! You bend down and examine the cracks in"
Writeln " the crypt. There seems to be nothing there"
ReDispMenu FALSE
Return
Endif
WriteBlock/EndBlock
────────────────────────────────────────────────────────
Syntax : WriteBlock
<.. Text to Display ..>
<.. More Text ..>
EndBlock
Description : This command will display the text between the Starting
WriteBlock and the EndBlock command.
Notes : Useful when displaying many lines of text to the player.
Text is sent _exactly_ as you type it, including any leading
spaces in the code.
Example :
WriteBlock
`c `9You have entered the crypt of the deceased former Lord of Shamile `%:
`4 Lord Hamilton`9. Lord Hamilton was the most influential and extravagant
`9 ruler Shamile has ever seen. It is rumored that he made a pact with the
`9 devil himself to win himself popularity, riches and influence. Noone is
`9 still alive who can tell all of the machinations of his time, but several
`9 journals have been unaccounted for. The town sages claim that these tombs
`9 have within their walls hidden compartments which hide the very items that
`9 may reveal a little more about Lord Hamilton''s past and whether his pact
`9 with the devil is what has brought about this plague on the realm.
EndBlock
SCRIPTS.DOC Page 30
─═════════════════════════════════════════════════════════════════════════─
Command Descriptions :
AddFlag
────────────────────────────────────────────────────────
Syntax : AddFlag <Name_of_Flag> <Value_of_Flag> <reset_value> <type>
Description : This command will set a semi-permanent flag on the character,
script, or game that is written to a file for saving.
Notes : There are so many uses for this, its only limit is your
creativity. It can be used to tie two ExMODs together by
having a character bring an object (saved as a flag) from one
script to a NPC in another! It can also be used to make
your ExMOD visitable only once by a character per day (with
the use of the reset_value set to daily and having the script
set a flag to the character when they come in the first time
and have it halt if the flag has already been set the next
time they come in!)
Name_of_Flag and Value_of_Flag must be a single word
(i.e. NO SPACES!) use the underscore (_) to seperate words
in it if you use them.
The <type> of flag specifies how it is accessed.
Type can have the following values:
Value: Where Located:
------------------------------------
M On the main portion of the game
S On only your script file
C On the character
Where the flag is located restricts what can or cannot access
that flag. If you were to place it on the main portion of the
game, any script/EXMOD could access it, and it should be
available for all characters (i.e. nothing character specific)
If you were to place it on only your script file, only your
script could access it, and, again, it should be available for
all characters. If you place it on the character, then, that
flag becomes available for all scripts/EXMOD's to use, but it
is only available when it is that character performing the
actions.
Reset value determines when the flag gets removed.
It can have the following values:
Value: When Removed:
------------------------------------
0 When the character dies*
1 Daily
2 Only by a RemoveFlag command
*Only usable if the type is set to C - character.
Using a reset_value of 0 is a good idea for flags to
represent things like items carried, information learned, or
anything that would seem reasonable.
SCRIPTS.DOC Page 31
─═════════════════════════════════════════════════════════════════════════─
Command Descriptions :
AddFlag (cont.)
A use of the daily reset type is some action should only occur
once per day, if it is something that a character can solve,
or a daily winner of the lottery, then use this reset type.
The reset_value of 2 is a special one as it will only go away
if a script calls a RemoveFlag on that exact variable (or in
the case of placing it on a character, it will go away when the
character gets deleted by daily maintenance), so its uses
should be restricted to things that should be maintained over
a period of time. Curses (for characters), the name of the
kings favored adventurer or the name of the character who has
solved your adventure the most. These are the variables
that are significant people and values and for characters,
things that are _SO_ significant that even death itself should
not remove this flag.
Flag naming convention:
Use a unique word that is associated with your script as the
first word, then use an underscore and then the name of the
flag i.e.
CRYPT_FOUND_KEY
CRYPT_OPENED_WALL
RemoveFlag
────────────────────────────────────────────────────────
Syntax : RemoveFlag <Name_of_Flag> <type>
Description : This command will remove a flag that has been set on the
character.
Notes : This is the only way to remove a flag that was set with the
reset value set to 2. It can also be used when a quest is
complete to remove all flags that were used in the quest.
The <type> of flag specifies where to remove the flag from.
Type can have the following values:
Value: Where to Remove From:
------------------------------------
M From the main portion of the game
S From your script file
C From the character's flag file
SCRIPTS.DOC Page 32
─═════════════════════════════════════════════════════════════════════════─
Command Descriptions :
FlagValue
────────────────────────────────────────────────────────
Syntax : FlagValue <Variable> <Name_of_Flag> <type>
Description : This command will return the value of a flag from the
characters file and assign it into the variable specified
in <Varialbe>
Notes : This is how you can do tests to see if a character or
a script or the main portion of the game has a
particular flag set, and if so, what the value is.
If the desired type has the flag, the value is placed into the
^VR type variable specified. If it does not exist, a value
of -1 is placed into the variable.
The <type> of flag specifies where to look to get the value.
Type can have the following values:
Value: Where to Retrive From:
------------------------------------
M From the main portion of the game
S From your script file
C From the character's flag file